<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<topic id="topic1">
      <title>plcontainer </title>
      <body>
        <p>The <codeph>plcontainer</codeph> utility installs Docker images and manages the
          PL/Container configuration. The utility consists of two sets of commands.</p>
        <ul id="ul_lzy_xsw_gcb">
          <li><codeph>image-*</codeph> commands manage Docker images on the Greenplum Database
            system hosts. </li>
          <li><codeph>runtime-*</codeph> commands manage the PL/Container configuration file on the
            Greenplum Database instances. You can add Docker image information to the PL/Container
            configuration file including the image name, location, and shared folder information.
            You can also edit the configuration file.</li>
        </ul>
        <p>To configure PL/Container to use a Docker image, you install the Docker image on all the
          Greenplum Database hosts and then add configuration information to the PL/Container
          configuration. </p>
        <p>PL/Container configuration values, such as image names, runtime IDs, and parameter values
          and names are case sensitive.</p>
        <section>
          <title>plcontainer Syntax</title>
          <codeblock>plcontainer [&lt;command>] [-h | --help]  [--verbose]</codeblock>
          <p>Where &lt;command> is one of the following.</p>
          <codeblock>  image-add {{-f | --file} &lt;image_file> [-ulc | --use_local_copy]} | {{-u | --URL} &lt;image_URL>}
  image-delete {-i | --image} &lt;image_name>
  image-list

  runtime-add {-r | --runtime} &lt;runtime_id>
     {-i | --image} &lt;image_name> {-l | --language} {python | python3 | r}
     [{-v | --volume} &lt;shared_volume> [{-v| --volume} &lt;shared_volume>...]]
     [{-s | --setting} &lt;param=value> [{-s | --setting} &lt;param=value> ...]]
  runtime-replace {-r | --runtime} &lt;runtime_id>
     {-i | --image} &lt;image_name> -l {r | python}
     [{-v | --volume} &lt;shared_volume> [{-v | --volume} &lt;shared_volume>...]]
     [{-s | --setting} &lt;param=value> [{-s | --setting} &lt;param=value> ...]]
  runtime-show {-r | --runtime} &lt;runtime_id>
  runtime-delete {-r | --runtime} &lt;runtime_id>
  runtime-edit [{-e | --editor} &lt;editor>]
  runtime-backup {-f | --file} &lt;config_file>
  runtime-restore {-f | --file} &lt;config_file>
  runtime-verify</codeblock>
        </section>
        <section>
          <title>plcontainer Commands and Options</title>
        </section>
        <parml>
          <plentry>
            <pt>image-add <varname>location</varname></pt>
            <pd>Install a Docker image on the Greenplum Database hosts. Specify either the location
              of the Docker image file on the host or the URL to the Docker image. These are the
              supported location options:<ul id="ul_ihd_dsv_gcb">
                <li>{<b>-f</b> | <b>--file</b>} <varname>image_file</varname> Specify the file
                  system location of the Docker image tar archive file on the local host. This example
                  specifies an image file in the <codeph>gpadmin</codeph> user's home directory:
                    <codeph>/home/gpadmin/test_image.tar.gz</codeph></li>
                <li>{<b>-u</b> | <b>--URL</b>} <varname>image_URL</varname> Specify the URL of the
                  Docker repository and image. This example URL points to a local Docker repository
                    <codeph>192.168.0.1:5000/images/mytest_plc_r:devel</codeph></li>
              </ul></pd>
              <pd>By default, the <codeph>image-add</codeph> command copies the image to each
                Greenplum Database segment and standby master host, and installs the image.
                When you specify an <varname>image_file</varname> and provide the
                [<b>-ulc</b> | <b>--use_local_copy</b>] option, <codeph>plcontainer</codeph>
                installs the image only on the host on which you run the command.</pd>
            <pd>After installing the Docker image, use the <xref
            href="#topic_rw3_52s_dw/runtime_add" format="dita">runtime-add</xref> command to
          configure PL/Container to use the Docker image.</pd>
          </plentry>
          <plentry>
            <pt>image-delete {<b>-i</b> | <b>--image</b>} <varname>image_name</varname></pt>
            <pd>Remove an installed Docker image from all Greenplum Database hosts. Specify the full
              Docker image name including the tag for example
                <codeph>pivotaldata/plcontainer_python_shared:1.0.0</codeph></pd>
          </plentry>
          <plentry>
            <pt>image-list</pt>
            <pd>List the Docker images installed on the host. The command list only the images on
              the local host, not remote hosts. The command lists all installed Docker images,
              including images installed with Docker commands.</pd>
          </plentry>
          <plentry id="runtime_add">
            <pt>runtime-add <varname>options</varname></pt>
            <pd>Add configuration information to the PL/Container configuration file on all
              Greenplum Database hosts. If the specified <varname>runtime_id</varname> exists, the
              utility returns an error and the configuration information is not added. </pd>
            <pd>These are the supported options:</pd>
            <pd>
              <parml>
                <plentry>
                  <pt>{<b>-i</b> | <b>--image</b>} <varname>docker-image</varname></pt>
                  <pd>Required. Specify the full Docker image name, including the tag, that is
                    installed on the Greenplum Database hosts. For example
                      <codeph>pivotaldata/plcontainer_python:1.0.0</codeph>. </pd>
                  <pd>The utility returns a warning if the specified Docker image is not
                    installed.</pd>
                  <pd>The <codeph>plcontainer image-list</codeph> command displays installed image
                    information including the name and tag (the Repository and Tag columns).</pd>
                </plentry>
                <plentry>
                  <pt>{<b>-l</b> | <b>--language</b>} python | python3 | r</pt>
                  <pd>Required. Specify the PL/Container language type, supported values are
                      <codeph>python</codeph> (PL/Python using Python 2), <codeph>python3</codeph>
                    (PL/Python using Python 3) and <codeph>r</codeph> (PL/R). When adding
                    configuration information for a new runtime, the utility adds a startup command
                    to the configuration based on the language you specify.</pd>
                  <pd>Startup command for the Python 2
                    language.<codeblock>/clientdir/pyclient.sh</codeblock></pd>
                  <pd>Startup command for the Python 3
                    language.<codeblock>/clientdir/pyclient3.sh</codeblock></pd>
                  <pd>Startup command for the R
                    language.<codeblock>/clientdir/rclient.sh</codeblock></pd>
                </plentry>
                <plentry>
                  <pt>{<b>-r</b> | <b>--runtime</b>} <varname>runtime_id</varname>
                  </pt>
                  <pd>Required. Add the runtime ID. When adding a <codeph>runtime</codeph> element
                    in the PL/Container configuration file, this is the value of the
                      <codeph>id</codeph> element in the PL/Container configuration file. Maximum
                    length is 63 Bytes.</pd>
                  <pd>You specify the name in the Greenplum Database UDF on the <codeph>#
                  container</codeph> line. </pd>
                </plentry>
                <plentry>
                  <pt>{<b>-s</b> | <b>--setting</b>}
                      <varname>param</varname>=<varname>value</varname></pt>
                  <pd>Optional. Specify a setting to add to the runtime configuration information.
                You can specify this option multiple times. The setting applies to the runtime
                configuration specified by the <varname>runtime_id</varname>. The parameter is the
                XML attribute of the <xref href="#topic_ojn_r2s_dw/plc_settings" format="dita"
                  >settings</xref> element in the PL/Container configuration file. These are valid
                  parameters.<ul id="ul_dsz_j4w_gcb">
                  <li><codeph>cpu_share</codeph> - Set the CPU limit for each container in the
                    runtime configuration. The default value is 1024. The value is a relative
                    weighting of CPU usage compared to other containers.</li>
                  <li><codeph>memory_mb</codeph> - Set the memory limit for each container in the
                    runtime configuration. The default value is 1024. The value is an integer that
                    specifies the amount of memory in MB. </li>
                  <li><codeph>resource_group_id</codeph> - Assign the specified resource group to
                    the runtime configuration. The resource group limits the total CPU and memory
                    resource usage for all containers that share this runtime configuration. You
                    must specify the <codeph>groupid</codeph> of the resource group. For information
                    about managing PL/Container resources, see <xref href="#topic_resmgmt"
                      format="dita">About PL/Container Resource Management</xref>.</li>
                  <li><codeph>roles</codeph> - Specify the Greenplum Database roles that are allowed
                    to run a container for the runtime configuration. You can specify a single role
                    name or comma separated lists of role names. The default is no restriction.</li>
                  <li><codeph>use_container_logging</codeph> - Enable or disable Docker logging for
                    the container. The value is either <codeph>yes</codeph> (enable logging) or
                      <codeph>no</codeph> (disable logging, the default). <p>The Greenplum Database
                      server configuration parameter <xref
                        href="../../ref_guide/config_params/guc-list.xml#log_min_messages"
                        scope="peer">log_min_messages</xref> controls the log level. The default log
                      level is <codeph>warning</codeph>. For information about PL/Container log
                      information, see <xref href="#plc_notes" format="dita">Notes</xref>.</p></li>
                </ul></pd>
                </plentry>
                <plentry>
                  <pt>{<b>-v</b> | <b>--volume</b>} <varname>shared-volume</varname></pt>
                  <pd>Optional. Specify a Docker volume to bind mount. You can specify this option
                    multiple times to define multiple volumes.</pd>
                  <pd>The format for a shared volume:
                        <codeph><varname>host-dir</varname>:<varname>container-dir</varname>:[rw|ro]</codeph>.
                    The information is stored as attributes in the <codeph>shared_directory</codeph>
                    element of the <codeph>runtime</codeph> element in the PL/Container
                    configuration file. <ul id="ul_nms_vvv_gcb">
                      <li><varname>host-dir</varname> - absolute path to a directory on the host
                        system. The Greenplum Database administrator user (gpadmin) must have
                        appropriate access to the directory.</li>
                      <li><varname>container-dir</varname> - absolute path to a directory in the
                        Docker container.</li>
                      <li><codeph>[rw|ro]</codeph> - read-write or read-only access to the host
                        directory from the container. </li>
                    </ul></pd>
                  <pd>When adding configuration information for a new runtime, the utility adds this
                    read-only shared volume information. </pd>
                  <pd>
                    <codeblock>&lt;greenplum-home>/bin/plcontainer_clients:/clientdir:ro</codeblock>
                  </pd>
                  <pd>If needed, you can specify other shared directories. The utility returns an
                    error if the specified <varname>container-dir</varname> is the same as the one
                    that is added by the utility, or if you specify multiple shared volumes with the
                    same <varname>container-dir</varname>.
                    <note type="warning">Allowing read-write access to a host directory requires
                      special considerations.<ul id="ul_ibw_gvk_kcb">
                        <li>When specifying read-write access to host directory, ensure that the
                          specified host directory has the correct permissions. </li>
                        <li>When running PL/Container user-defined functions, multiple concurrent
                          Docker containers that are running on a host could change data in the host
                          directory. Ensure that the functions support multiple concurrent access to
                          the data in the host directory.</li>
                      </ul></note></pd>
                </plentry>
              </parml>
            </pd>
          </plentry>
          <plentry>
            <pt>runtime-backup {<b>-f</b> | <b>--file</b>} <varname>config_file</varname></pt>
            <pd>
              <p dir="ltr">Copies the PL/Container configuration file to the specified file on the
                local host. </p>
            </pd>
          </plentry>
          <plentry>
            <pt>runtime-delete {<b>-r</b> | <b>--runtime</b>} <varname>runtime_id</varname></pt>
            <pd>
              <p dir="ltr">Removes runtime configuration information in the PL/Container
                configuration file on all Greenplum Database instances. The utility returns a
                message if the specified <varname>runtime_id</varname> does not exist in the
                file.</p>
            </pd>
          </plentry>
          <plentry>
            <pt>runtime-edit [{<b>-e</b> | <b>--editor</b>} <varname>editor</varname>]</pt>
            <pd>Edit the XML file <codeph>plcontainer_configuration.xml</codeph> with the specified
              editor. The default editor is <codeph>vi</codeph>.<p>Saving the file updates the
                configuration file on all Greenplum Database hosts. If errors exist in the updated
                file, the utility returns an error and does not update the file.</p></pd>
          </plentry>
          <plentry>
            <pt>runtime-replace <varname>options</varname></pt>
            <pd>
              <p dir="ltr">Replaces runtime configuration information in the PL/Container
                configuration file on all Greenplum Database instances. If the
                  <varname>runtime_id</varname> does not exist, the information is added to the
                configuration file. The utility adds a startup command and shared directory to the
                configuration. </p>
              <p dir="ltr">See <xref href="#topic_rw3_52s_dw/runtime_add" format="dita"
              >runtime-add</xref> for command options and information added to the
            configuration.</p>
            </pd>
          </plentry>
          <plentry>
            <pt>runtime-restore {<b>-f</b> | <b>--file</b>} <varname>config_file</varname></pt>
            <pd>
              <p dir="ltr">Replaces information in the PL/Container configuration file
                  <codeph>plcontainer_configuration.xml</codeph> on all Greenplum Database instances
                with the information from the specified file on the local host.</p>
            </pd>
          </plentry>
          <plentry>
            <pt>runtime-show [{<b>-r</b> | <b>--runtime</b>} <varname>runtime_id</varname>]</pt>
            <pd>
              <p dir="ltr">Displays formatted PL/Container runtime configuration information. If a
                  <varname>runtime_id</varname> is not specified, the configuration for all runtime
                IDs are displayed.</p>
            </pd>
          </plentry>
          <plentry>
            <pt>runtime-verify</pt>
            <pd>
              <p dir="ltr">Checks the PL/Container configuration information on the Greenplum
                Database instances with the configuration information on the master. If the utility
                finds inconsistencies, you are prompted to replace the remote copy with the local
                copy. The utility also performs XML validation.</p>
            </pd>
          </plentry>
          <plentry>
            <pt><b>-h</b> | <b>--help</b></pt>
            <pd>Display help text. If specified without a command, displays help for all
                <codeph>plcontainer</codeph> commands. If specified with a command, displays help
              for the command.</pd>
          </plentry>
          <plentry>
            <pt><b>--verbose</b></pt>
            <pd>Enable verbose logging for the command.</pd>
          </plentry>
        </parml>
        <section>
          <title>Examples</title>
          <p>These are examples of common commands to manage PL/Container:</p>
          <ul id="ul_ijd_xmw_gcb">
            <li>Install a Docker image on all Greenplum Database hosts. This example loads a Docker
              image from a file. The utility displays progress information on the command line as
              the utility installs the Docker image on all the
                hosts.<codeblock>plcontainer image-add -f plc_newr.tar.gz</codeblock><p>After
                installing the Docker image, you add or update a runtime entry in the PL/Container
                configuration file to give PL/Container access to the Docker image to start Docker
                containers.</p></li>
            <li>Install the Docker image only on the local Greenplum Database host:
                <codeblock>plcontainer image-add -f /home/gpadmin/plc_python_image.tar.gz --use_local_copy</codeblock>
            </li>
            <li>Add a container entry to the PL/Container configuration file. This example adds
              configuration information for a PL/R runtime, and specifies a shared volume and
              settings for memory and logging.
                <codeblock>plcontainer runtime-add -r runtime2 -i test_image2:0.1 -l r \
  -v /host_dir2/shared2:/container_dir2/shared2:ro \
  -s memory_mb=512 -s use_container_logging=yes</codeblock><p>The
                utility displays progress information on the command line as it adds the runtime
                configuration to the configuration file and distributes the updated configuration to
                all instances.</p></li>
            <li>Show specific runtime with given runtime id in configuration
                file<codeblock>plcontainer runtime-show -r plc_python_shared</codeblock><p>The
                utility displays the configuration information similar to this
                output.<codeblock>PL/Container Runtime Configuration:
---------------------------------------------------------
 Runtime ID: plc_python_shared
 Linked Docker Image: test1:latest
 Runtime Setting(s):
 Shared Directory:
 ---- Shared Directory From HOST '/usr/local/greenplum-db/bin/plcontainer_clients' to Container '/clientdir', access mode is 'ro'
 ---- Shared Directory From HOST '/home/gpadmin/share/' to Container '/opt/share', access mode is 'rw'
---------------------------------------------------------</codeblock></p></li>
            <li>Edit the configuration in an interactive editor of your choice. This example edits
              the configuration file with the vim
                editor.<codeblock>plcontainer runtime-edit -e vim</codeblock><p>When you save the
                file, the utility displays progress information on the command line as it
                distributes the file to the Greenplum Database hosts. </p></li>
            <li>Save the current PL/Container configuration to a file. This example saves the file
              to the local file
              <codeph>/home/gpadmin/saved_plc_config.xml</codeph><codeblock>plcontainer runtime-backup -f /home/gpadmin/saved_plc_config.xml</codeblock></li>
            <li>Overwrite PL/Container configuration file with an XML file. This example replaces
              the information in the configuration file with the information from the file in the
                <codeph>/home/gpadmin</codeph>
              directory.<codeblock>plcontainer runtime-restore -f /home/gpadmin/new_plcontainer_configuration.xml</codeblock>The
              utility displays progress information on the command line as it distributes the
              updated file to the Greenplum Database instances. </li>
          </ul>
        </section>
      </body>
    </topic>
